Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

build(docs): set site_url from ReadTheDocs env var #13685

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

build(docs): set site_url from ReadTheDocs env var #13685

wants to merge 1 commit into from
+1 −0

Conversation

agilgur5
Copy link
Member

@agilgur5 agilgur5 commented Oct 1, 2024 •
edited
Loading

Motivation

Modifications

  • Add site_url config to mkdocs.yml

Verification

  1. mkdocs serve
  2. Go to http://127.0.0.1:8000/en/latest/ now -- works
  3. Go to http://127.0.0.1:8000/en/latest/sitemap.xml -- actually has content now
  4. Go to http://127.0.0.1:8000/en/latest/wrong -- has a properly styled 404 page.
    Screenshot: Screenshot 2024-10-26 at 11 55 40 PM

@agilgur5
build(docs): set site_url from ReadTheDocs env var
28026b6 
- `site_url` is [required](https://stackoverflow.com/a/59295885/3431180) for canonicalization and creating a `sitemap.xml`

- Also for certain features like:
  - Instant loading: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=site+url#instant-loading
  - Versioning (we use RTD's versioning, but may want some features from here): https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/?h=site+url#publishing-a-new-version

Signed-off-by: Anton Gilgur <[email protected]>
@agilgur5 agilgur5 added area/docs Incorrect, missing, or mistakes in docs area/build Build or GithubAction/CI issues labels Oct 1, 2024
@agilgur5
Copy link
Member Author

agilgur5 commented Oct 18, 2024 •
edited
Loading

  • site_url is required for canonicalization and creating a sitemap.xml
  • Also for certain features like:

Ah I think site_url was also required for to make 404 links (like https://argo-workflows.readthedocs.io/en/release-3.4/wrong) render CSS properly, and that was the original purpose of this PR, but I've forgotten what links I followed (went down a rabbit hole at the time). mkdocs/mkdocs#2318 is related

@agilgur5
Copy link
Member Author

Ah I think site_url was also required for to make 404 links (like https://argo-workflows.readthedocs.io/en/release-3.4/wrong) render CSS properly, and that was the original purpose of this PR, but I've forgotten what links I followed (went down a rabbit hole at the time).

Found it again: https://docs.readthedocs.io/en/stable/reference/404-not-found.html, under the MkDocs tab:

MkDocs automatically generates a 404.html which Read the Docs will use. However, assets will not be loaded correctly unless you define the site_url configuration value as your site’s canonical base URL.

@agilgur5 agilgur5 marked this pull request as ready for review October 27, 2024 04:08
@agilgur5 agilgur5 added the prioritized-review For members of the Sustainability Effort label Oct 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
area/build Build or GithubAction/CI issues area/docs Incorrect, missing, or mistakes in docs prioritized-review For members of the Sustainability Effort
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@agilgur5